Collection of Tools & Utilities/Collection of Tools and Utilities.iso/batchut/echsys10.zip/ECHOSYS.DOC

Text File | 1989-09-25 | 10KB | 231 lines

                   E C H O S Y S  /  E N V S Y S  1.0
                   ==================================

                       TapirSoft Gisbert W.Selke
                             September 1989


This is sort of an enhancement to the DOS ECHO and SET commands. In
addition to echoing a string to StdOut or setting an environment
variable, various information about the system may be included
according to the user's wishes, e.g., current drive/directory, date and
time, free memory, DOS and BIOS version, and many others. In addition,
a DOS error level is set to reflect the latest of actions, where
possible.


There are two main reasons for wanting this: for logging purposes, and
for passing system information to programmes or to environment
variables. Nearly all this information is available one way or the other
via standard DOS commands (DATE, VER, CHKDSK, ...); unfortunately, it is
invariably bundled up with other text, so that it is hard to get at the
main information. (Ever tried to record the current drive/directory in
order to be able to switch back later? Yes, it's possible, but it's
roundabout at best.)


EchoSys will just copy its command line to StdOut, unless it encounters
its special marker, by default '^'. The character right after this
marker tells EchoSys what sort of information to include before
resuming normal processing. Note that EchoSys by itself appends no
carriage return/line feed at the end of the string - you'll have to do
that yourself (cf. example below).


E.g., to create a batch file that records the current drive and
directory in environment variables, you might say

      echosys  set drive=^:^x0d^x0a>savedir.bat
      echosys  set   dir=^\^x0d^x0a>>savedir.bat

Executing SAVEDIR.BAT will now record the pertinent data in the
environment variables given.

Note, in the example above, the hex codes that work out as the usual
line terminator bytes.

A simpler, equivalent script runs as follows:

      echosys  set drive=^:^x0d^x0aset dir=^\>savedir.bat

We can leave off the final carriage return/linefeed, because DOS does
not need them. (Neither does it need a Ctrl-Z at the end of a file.)

An example for logging system usage is the following line, included in a
batch file that starts some programme:

      echosys MapView started on ^W, ^D^/^M, at ^h^-^m\x0d\x0a

Again, note the use of the line end bytes.


For the status of LPT1, '^L', several bits are added as follows:

 1 time out       8 I/O error      16 selected       32 out of paper
64 acknowledge  128 not busy


The sequence '^K' is slightly different: the user is expected to type a
single letter, which is inserted into the output before the rest of the
line is processed. Only ASCII letters are accepted; extended keys (like
function or cursor keys) are ignored.


Wherever possible, EchoSys sets a DOS error level equalling the
numerical value of the last special sequence output; e.g., after '^:'
the error level will be 67, the ASCII code for 'C', if and only if the
current disk is drive C:. In some cases, this will be meaningless; in
particular, '^\' does not affect the error level, '^F' and '^T' will
return a value in 1000 KN, which may not be much use, and so forth. The
PC type, command '^t', will be a code as follows:

0 unknown     1 Model 80    2 Ap          3 Model 30    4 unknown
5 AT          6 PC Junior   2 XT          3 PC

Of the currency symbol, '^$', only the first character will be returned.
An important way to use this feature, however, is for prompts in menus,
e.g.,

      echosys It is now ^h^-^m. Enter your choice (A/B/C): ^K Thank you.

On return, the error level will be set to the ASCII value of the key
typed by the user (note that the values of the earlier commands in the
line will be discarded in favour of the last one). A batch file would
now proceed to take action based on that error level. Keep in mind that
the input is case significant, so you might want to check for both 65
and 97 to catch 'A' and 'a', etc.


A complete list of the special designators follows:

: current drive                         \ current directory
F free disk space (in KBytes)           T total disk space (in KBytes)
R free RAM (in KBytes)                  r RAM size (in KBytes)
l number of logical drives              f number of floppies installed
P number of parallel printer ports      S number of communication ports
7 is coprocessor installed? (0 or 1)    V current video mode
w screen width                          t type of PC
v DOS version                           b BIOS version
i "<" symbol                            o ">" symbol
p "|" symbol                            O options char (switch char)
x character given by next 2 hex digits  K key typed by user
D day                                   M month
Y year                                  W weekday
h hour                                  m minute
s second                                c centisecond
/ date separator                        - time separator
k 1000s separator                       1 decimal separator
C country code                          $ currency string
L LPT1 status


Note that the command designator is case-dependent.


Any other character will be passed through unaltered; in particular, the
sequence '^^' will put one '^' into the output.


Calling EchoSys without any parameters (and I mean *without*, i.e., even
without a trailing blank) will display a short help screen, so that you
don't need to remember all those cryptic designators.


EnvSys works very much alike, but does not output anything (as long as
it is called with at least one parameter), but sends all its output to
an environment variable instead. The name of this variable must be the
first argument on the command line. E.g., the drive/directory saving
examples from above may be rewritten as

      envsys disk ^:
      envsys drive ^\

For many applications, this involves far less overhead than the methods
outlined above; on the other hand, there are things that you just cannot
do in this simpler way. - Note that there is no '=' between the variable
name and the string. - An empty string will remove the variable from the
environment; again, 'empty' is to be taken seriously. The environment is
checked for availability of room; no harm will be done in any case, but
no error condition is indicated to the user. (You can easily check for
success by examining the contents of the variable in question.)


If you are in a subordinate command shell, EnvSys will update both the
subordinate and the primary shell's environments, but not those of any
further intermediate shells that may lurk in the shadows.


Depending on the DOS version you use, some of the features may not work
properly; all this has been tested under MS-DOS 3.3. I wouldn't
recommend running it under DOS 1.x, though.


I have chosen the character '^' as a marker because it is rarely used
for other purposes (as opposed to, say, the more common '\'). If you
discover that you dislike my choice, you can either re-assemble with
the marker of your choosing (look for the definition of 'special'), or
you can directly patch EchoSys.Com with Debug or your favourite binary
editor; look for the string 'SPECIAL=' near the beginning of the file
and change the character right behind.


Two notes on style:

(i) Yeah, I know this utility is kind of crammy. It's not meant to be
used regularly from the command line, though; it's lean and mean and
it's for use in batch files where you once think about it and then
forget it. I tried to put in everything I could think of, so that I
need just one utility instead of dozens. (If I've forgotten something
you need, tell me...)

(ii) The assembler code is probably bad style, spaghetti and so forth.
Sorry about that; I'm not an assembler programmer at all.


Legal stuff:

Debug, DOS and its offspring are copyrighted by MicroSoft Corp.

Writing this wouldn't have been possible were it not for Ralf Brown's
excellent list of the interrupts used by